docs(react): shrink UNGATED_DOCS by one — the react README's 11 blocks compile (#5174 batch 12) - #7910

Part of #5174 — batch 12 of the check-doc-snippet-types ungated-docs ledger burn-down. The card stays open; 25 entries remain after this.

packages/react/README.md leaves UNGATED_DOCS and all 11 of its ts/tsx snippets now compile, --strict, against the packages' built dist/*.d.ts. Zero FRAGMENT_MARKER declarations added, zero UNGATED_DOCS entries added — the ledger hunk is git diff --numstat 0 2, removals only.

Ledger and coverage, measured

Both gates — origin/main's copy and this branch's — were imported side by side and evaluated over the same working tree, so the covered-set delta is attributable to the ledger alone and not to a moving tree.

declared fragments unmoved means every one of the 11 newly covered blocks earned it by compiling; not one was excused with a marker.

Programmatic invariants, printed rather than eyeballed:

LEDGER entry count: 26 -> 25
ADDED entries: []
REMOVED entries: ["packages/react/README.md"]
surviving entries whose REASON TEXT changed: []
COVERED documents: 201 -> 202  STRICTLY GROWS: true
previously-covered docs now UNGATED: []
build filters ADDED [] REMOVED []
scan-set size (documents): 227 -> 227

Gate strictness is unchanged and proved byte for byte: everything from the Fence scanning banner to EOF is identical on origin/main and on this branch — 1117 lines, sha256 91450911e867d61a6f6945d4ea649c894097252d664c792ea69388f230488d59 on both. The gate file is touched only inside the UNGATED_DOCS object literal.

Gate verdict at the final commit c97bd02cb, exit 0:

Scanned 227 document(s): 202 covered (100 of them hold a ts/tsx block), 25 ungated
Covered blocks: 625 — 467 to compile, 158 declared fragment(s).
Syntax phase:   every block parsed, so every one of them reached the semantic phase.
Semantic phase: 467 of 467 block(s) judged, 0 failed.
Every covered documentation snippet compiles against the built types.

What was wrong, and what the repairs are

Seven of the 11 blocks failed. Each is repaired at the document, following the shipped types — no type minted, no export added, no block weakened.

1. useSchemaContext taught an API that does not exist. The example destructured data and updateData. The shipped SchemaRendererContextType declares dataSource, debug, debugFlags and apiFetch, and neither of those two names (packages/react/dist/context/SchemaRendererContext.d.ts). That is the TS2339x2 half of the ledger entry's own reason, and it reproduces exactly. The example now reads what the context actually carries, and record data is pointed at useDataScope, which is the hook that answers it. The prose above it changed with the code.

2. The NON_GRID_ROW_CEILING block did not parse — and a reader copying it hit the same error. Its destructuring statement ended without a semicolon and the next statement opens with <, so ASI does not fire and applyNonGridRowCeiling(result) is parsed as the left side of a relational expression: five syntax errors, TS1005 x3 and TS1109 x2. One semicolon fixes it, with a comment saying why it is load-bearing.

3. The remaining five carried ambient names the page never defined. Those are now declare const against the shipped types, following the pattern packages/data-objectstack/README.md already uses (DataSource and QueryParams from @object-ui/types, ApiFetch from @object-ui/react), plus the two implicitly-any parameter lists given real annotations.

Two claims the prose only asserted are now enforced by the compiler:

• OBJECT_GRID_BINDING is annotated ElementDataSourceMapping. The paragraph beneath it says a mapping "names ONLY the keys this block reads … a composed value written onto a key the block ignores would be accepted and silently dropped — the defect the binding exists to remove." That is now a compile error rather than a sentence (probe P2).
• notify()'s severity and displayType literals are checked against the spec unions (probe P1).

The ledger entry's reason text was STALE — reported, not reproduced

The entry read 9 undefined-name diagnostic(s) …; plus TS2339x2 — candidate real defects, un-triaged. What actually reproduced at the branch point was 8 undefined-name plus 4 implicit-any, and — the part the reason does not mention at all — 1 parse failure with 5 diagnostics, in the NON_GRID_ROW_CEILING block that objectui#7210 added after the reason was written. The TS2339x2 half reproduced exactly. A ledger reason is a snapshot of a document that keeps moving; this one had drifted, and the drift is recorded here rather than copied forward.

The labelled-block-statement trap: the negative, stated

Checked per block. Absent from this document, in the strong form: not one of the 11 blocks is a brace-wrapped object literal at all — every block opens with an import statement or a const destructuring. The trap needs a single-key brace-wrapped literal to parse as a labelled block statement and stay green under any spelling; there was no candidate here, single-key or multi-key. So no block in this document was green-under-any-spelling before this change.

Non-vacuity: six planted probes, direction predicted IN WRITING before each run

Predictions were written to a file before the first probe ran. No build artifact sits between a mutation and the thing under test — every mutation edits markdown the gate reads straight from disk, and the dist/ it compiles against is untouched — so no rebuild was needed on either leg, and that is stated rather than assumed. Each leg proved the mutation reached disk (git hash-object differing from the HEAD blob, with an equal hash treated as "this probe did not run" and aborting) and each restore was proved by an empty git diff HEAD plus a blob hash equal to the HEAD blob, never inferred from an exit code. Every probe was run twice — once at f81d879f4 and again at the merged head c97bd02cb — with identical diagnostics.

Two honest notes on the table. P2's exact code was predicted as TS2353 and observed as TS2561; the direction predicted was RED and the observed diagnostic is the same fact with a spelling suggestion attached. P4's textual before/after counting is degenerate because the post-mutation text is a prefix of the pre-mutation text — the discriminators there are the differing blob hash and the syntax-phase line flipping from "every block parsed" to "1 block(s) failed to parse".

The bound of the green, published rather than left to be found

P5 was predicted GREEN in writing and observed GREEN. SchemaRendererProvider declares dataSource: any in the shipped types, so the SchemaRendererProvider block cannot check what the host injects: replacing the adapter with a bare string raises nothing. That is a real limit of this document's new coverage and it is stated here rather than hidden behind the exit code. It is the same class as objectui#7483 (a props parameter typed bare any makes a wrong prop raise nothing), on a different consumer.

P2 and P6 bound it from the other side: a type without an index signature does catch a wrong key (ElementDataSourceMapping), and a declared member's value type is checked even where the surrounding type is open (SchemaRendererProps.schema refuses number, which its own docblock says is excluded deliberately).

Gates run locally, each quoting its own printed verdict

All at c97bd02cb, exit codes captured by redirect before any pipe, never read after one. git status --porcelain empty at measurement time and after all twelve probe runs.

A manual grep -naP over the C0 control-byte set on both changed files returned no hits, on top of the gate.

lint:root is not a narrowing, three pieces: the population read from eslint's own --format json is 252 files of which 0 are .md/.mdx (so the edited README is outside lint's population entirely); the one changed file inside that population, scripts/check-doc-snippet-types.mjs, reports errorCount 0 warningCount 0; and eslint.config.js sets no project / projectService / tsconfigRootDir, so type-aware linting is off and this diff cannot move the verdict on a file it does not touch.

Vitest, from the repo root, --maxWorkers=2, exit 0: Test Files 13 passed (13) / Tests 545 passed (545). The suite set was derived by git grep -l for the gate's name and for the edited document, and includes scripts/__tests__/check-doc-snippet-types.test.ts — the edited script's own suite, which is owed separately from the doc-gate family. The derived set was identical before and after the merge below.

No changeset — and why, since the dispatch assumed otherwise

scripts/check-changeset-presence.mjs, which AGENTS.md names as the authority, exits 0 with 2 file(s) changed, 0 of them published source of a package the release covers … no changeset is owed: a packages/*/README.md ships inside the package but *.md is subtracted from the files judgement, and scripts/ publishes nothing. Batches 10 and 11 landed the same shape with no changeset (c4f541df9, c39c825d3 — two files each). An empty-frontmatter changeset was written, measured against the gate, and then removed so this PR matches its own precedent and the gate's verdict.

Scope guard

origin/main moved to 84ce0b80d mid-run and was merged, never rebased. It touched four documents in the gate's scan surface (the objectui#7900 guide pages) but no non-test package source, so the built dist/ did not move; every figure above, all six probes included, was nonetheless re-taken after the merge at c97bd02cb, and the dist/index.d.ts of all 26 build-filter packages was confirmed present on disk in this worktree before any gate result was trusted.

Untouched, deliberately: packages/plugin-gantt/README.md and packages/plugin-kanban/README.md (#7302 / PARTIAL_EXCERPTS), packages/plugin-dashboard/README.md (its four untyped example blocks are #7035's), and content/docs/guide/architecture.md / layout.md / schema-rendering.md (PR #7900's, and not ledger entries).

Filed, not fixed here

Two findings were filed unassigned rather than ridden along on a ledger batch:

• finding(react): SchemaRendererProvider's dataSource prop and SchemaRendererContextType are typed any — a string passed where the host adapter belongs raises nothing #7912 — SchemaRendererProvider's dataSource prop and SchemaRendererContextType are typed any, which is what probe P5 above measures. Same class as finding(app-shell): ObjectView's entire props surface is typed any — a misspelled prop on a public route-level view raises nothing #7483, on the injection point for the whole renderer tree. Narrowing it to the published DataSource is a public-contract change with its own blast radius.
• finding(plugin-markdown): toc-anchor-parity cites packages/react/README.md by line address (:224) and the heading has moved to :253 — a citation nothing checks #7913 — packages/plugin-markdown/src/toc-anchor-parity.test.tsx:136 names its case by the line address packages/react/README.md:224; this diff moves that heading to :253. Nothing fails (the test asserts against an inline string and never reads the file), which is precisely why the citation rots silently. It is the class objectui#7853 ruled on, in another package's suite, so it stays out of this two-file diff.

Draft on purpose, not enqueued, auto-merge not enabled.

Generated by Claude Code